/**
 * @copyright Copyright (c) 2025 CSG Digital Grid Technology (Guangdong) Co., Ltd.
 * @author Xie Jinhui
 */

/**
 * @file app_execute.h
 * @brief Header file for application execution actions.
 * 
 * This header file defines the interface for application action execution
 * and validation functions. It serves as the main entry point for
 * application control operations including installation, uninstallation,
 * startup, shutdown, and information retrieval.
 */

/**
 * 
 * The application execution module provides centralized control over
 * application lifecycle management, including installation, removal,
 * activation, deactivation, and status monitoring. This interface
 * abstracts the underlying implementation details and provides a
 * consistent API for application management operations.
 */

/* 
 * Include guard to prevent multiple inclusions of this header file
 * This ensures that the compiler processes the declarations only once
 * during compilation, preventing redefinition errors and improving
 * compilation efficiency in large projects with multiple dependencies
 */
#ifndef APP_EXECUTE_H

/* 
 * Define the include guard macro to prevent multiple inclusion
 * This macro is checked at the beginning of the file and defined
 * immediately after to mark this header file as already processed
 */
#define APP_EXECUTE_H

/* 
 * Include the application action structure definition
 * This header contains the definition of struct app_action which
 * encapsulates all parameters needed for application control operations
 * including application name, package path, and operation flags
 */
#include "app_action.h"

/* 
 * Execute application actions based on the provided configuration
 * This is the primary function for performing application control operations
 * such as install, uninstall, start, stop, and information retrieval
 * 
 * @param app_args: Pointer to app_action structure containing operation parameters
 *                  This structure includes the application name, package path,
 *                  and specific operation flags that determine which action to perform
 * 
 * @return: Integer status code indicating operation result
 *          Returns 0 on successful execution, negative error codes on failure
 *          Error codes are defined in the common error definitions header
 * 
 * The function performs the following main operations:
 * 1. Validates input parameters using appaction_check
 * 2. Routes to specific operation handlers based on set flags
 * 3. Handles concurrent execution prevention
 * 4. Provides detailed error reporting for troubleshooting
 */
int appaction_exec(struct app_action *app_args);

/* 
 * Validate application action parameters for consistency and completeness
 * This function performs comprehensive validation of the app_action structure
 * to ensure all required parameters are present and logically consistent
 * 
 * @param app_args: Pointer to app_action structure to be validated
 *                  The function examines all fields including operation flags,
 *                  application names, and file paths for logical consistency
 * 
 * @return: Integer validation result code
 *          Returns 0 if all parameters are valid and consistent
 *          Returns negative error codes for specific validation failures
 *          including conflicting flags, missing parameters, or invalid combinations
 * 
 * Validation rules include:
 * - Only one operation flag can be set at a time
 * - Application name must be provided for operations that require it
 * - Package path must be specified for installation operations
 * - Logical consistency between operation type and required parameters
 */
int appaction_check(struct app_action *app_args);

/* 
 * End of include guard section
 * This marks the completion of the header file content and ensures
 * that subsequent inclusions of this file will be skipped due to
 * the previously defined APP_EXECUTE_H macro
 */
#endif // APP_EXECUTE_H